home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / lang / PPCcforth.lha / PPCcforth / forth.doc < prev    next >
Text File  |  1985-12-27  |  28KB  |  640 lines
  1. C-FORTH: a portable, C-coded figFORTH interpreter.
  2.  
  3. Written by Allan Pratt; completed April 1985.
  4.  
  5. This is a FORTH interpreter written entirely in portable C and FORTH. It
  6. requires nothing more than a decent C compiler to use.  It is not exactly
  7. fast or efficient, but it is a true FORTH interpreter.
  8.  
  9. The features include:
  10.  
  11. Bootstrapping threaded definitions from a near-FORTH dictionary file.
  12. Block file I/O.
  13. Execution tracing and single-stepping.
  14. Breakpoint detection, dumping the stack at the breakpoint.
  15. Saving and automatic restoration of the FORTH environment.
  16. Ability to convert the block file to a line-editor-compatible file, and back.
  17.  
  18. Included with the interpreter is a block file containing:
  19.  
  20. An UNTHREAD utility.
  21. A screen editor with key-binding and cursor-addressing.
  22.  
  23.  
  24. BRINGING UP THE INTERPRETER:
  25.  
  26. THIS FORTH MODEL REQUIRES "int"s TO BE TWICE THE SIZE OF "short"s,
  27. and "short"s to be 16 bits. I realize this is a barrier to portability,
  28. but you can change occurrances of "int" to "long" and "short" to "int" if
  29. "long"s are twice the size of "int"s.
  30.  
  31. Note also that model sizes greater than 32K (with 16-bit cells) are likely
  32. to fail because of the sign bit. This has not been adequately tested.
  33.  
  34. The first four sections of the file "common.h" contain implementation-dependent
  35. constants. These are TRACE, BREAKPOINT, several default file names, INITMEM,
  36. MAXMEM, and NSCR. As distributed, the FORTH system will work on most systems,
  37. but especially virtual-memory systems. If you do not have virtual memory, you
  38. will want to change MAXMEM -- see common.h for instructions.
  39.  
  40. Once you've configured common.h to your taste, compile the files with
  41.  
  42.     touch lex.yy.c
  43.     make all
  44.  
  45. Note that lex.yy.c is lex output from forth.lex, slightly modified (using
  46. sed). lex.yy.c is included in the distribution because not everybody has
  47. lex and sed. You touch lex.yy.c before make-ing so make doesn't try to remake
  48. it.
  49.  
  50. This make will create several files. Notable among them are "nf", the
  51. bootstrapper, "forth.core", the core-image output of nf, and "forth", the
  52. interpreter itself. Finally, there are two utility filters, b2l and l2b. These
  53. convert files from block format to line format and back (b2l --> block to
  54. line). A line-format file is one suitable for editing with vi or emacs: it
  55. consists of a header line for each screen, followed by 16 newline-separated
  56. lines of text for that screen, followed by the next screen. THERE MUST ALWAYS
  57. BE SIXTEEN LINES BETWEEN HEADERS in the line file, or l2b won't work properly.
  58.  
  59. You must use l2b to create the block file "forth.block" from "forth.line". Use:
  60.  
  61.     l2b < forth.line > forth.block
  62.  
  63. to do this.  If you don't have I/O redirection, I'm afraid you'll have to
  64. patch these programs (and lex.yy.c and nf.c, for that matter) to take 
  65. arguments or use default files.
  66.  
  67. Note that "forth.block" is the default block file used by FORTH. You can change
  68. this default in "common.h", and you can change it on the FORTH command line
  69. with -f.
  70.  
  71. Now that you have the interpreter ("forth"), the block file
  72. ("forth.block"), and the core file ("forth.core"), you are ready to
  73. roll. Invoke FORTH with the following line to the C-shell:
  74.  
  75.     stty -echo cbreak ; forth ; stty echo -cbreak
  76.  
  77. Some notes while running FORTH:
  78.  
  79. The backspace character is ^H, no matter what your terminal is set for. When
  80. you backspace, ASCII 8 gets sent to the screen, so the cursor should back up
  81. but not erase the letter you're backing up over. There is no kill character
  82. to wipe out an entire line. If you backspace beyond the beginning of the line,
  83. you will get a beep.
  84.  
  85. Don't use tabs; FORTH doesn't recognize them as whitespace.
  86.  
  87. Everything in the FORTH world is upper-case. Use caps-lock if you have one.
  88.  
  89. The VLIST command lists the FORTH vocabulary.
  90.  
  91. Some commands, like LIST and VLIST, use the FORTH word ?TERMINAL to see
  92. if the user wants to quit. Use your interrupt character (usually ^C) to
  93. stop these commands.  If you hit ^C twice before ?TERMINAL is checked,
  94. then you'll get an ABORT back to the FORTH top level. If the FORTH program
  95. is waiting for keyboard input, you'll have to hit ^C twice and then hit
  96. a normal key to see this effect. Your Quit character (often ^\) still works
  97. to get you back to your shell.
  98.  
  99. When you start FORTH up, it will tell you the number of blocks in the
  100. block file (either the default or the one you specified with -f). You can
  101. see a block with the LIST command: "3 LIST" will list block number 3. Block
  102. zero is special: because of a bug in the FORTH standard model, you can't
  103. see block zero until you've accessed many other blocks (where "many" is the
  104. number NSCR from "common.h").
  105.  
  106. In any case, you can load the UNTHREAD utility (see below) with "1 LOAD"
  107. (because it starts on block 1), and the editor with "10 LOAD".
  108.  
  109. FORTH uses "setbuf(stdout,0)" in "forth.c" to force standard output to
  110. be unbuffered.  If this call doesn't work for you, just remove it, and
  111. standard output will be line buffered. If that is the case, change
  112. EXPECT (in "forth.dict"): replace the EMIT call with DROP. Then you can
  113. call forth directly, without the stty stuff. You use your own erase and kill
  114. characters, but the editor won't work.
  115.  
  116. SAVING THE FORTH ENVIRONMENT:
  117.  
  118. When you have been working in FORTH for a while, you will have developed
  119. words which you'd like to save, without having to reload them from the
  120. block file all the time. The word SAVE will save the current core image on
  121. a file, normally "forth.newcore", and exit. The -s flag changes the save
  122. file name.
  123.  
  124. When you start FORTH, the core file (either "forth.core" or the one specified
  125. with -c) is checked to see if it is a saved image or a bootstrapped image.
  126. If it's a saved image, execution begins from the spot it left off from.
  127. If it's bootstrapped (fresh out of nf), execution begins at COLD.
  128.  
  129. SUMMARY OF COMMAND-LINE OPTIONS:
  130.  
  131. -t[n]        trace; n is a digit from 0 to 9, default 0.
  132.  
  133.         Each time through the inner interpreter, a line will be printed
  134. out showing the current stack pointer, the top n stack elements
  135. (topmost at the left), the current interpretive pointer (ip), an indent
  136. to reflect the current nesting depth (actually the return-stack depth),
  137. and the name of the word about to be executed. N is the "trace depth";
  138. see DOTRACE below.
  139.  
  140. -d[n]        debug; n is a digit from 0 to 9, default 0.
  141.  
  142.     Like -t, -d prints out the trace line each time through the inner
  143. interpreter.  Unlike -t, it will then wait for input from the terminal. If
  144. you hit newline (Return, CR, etc.) it will proceed. If you type any key
  145. followed by newline, it will dump the current memory image to the dump file,
  146. usually "forth.dump", and then continue.
  147.  
  148. -n        no setbuf.
  149.     If -n is present, the setbuf(stdout,NULL) call which makes stdout
  150. unbuffered instead of line-buffered will not be executed. This is useful if
  151. you intend to do debugging with -t, -d, or the TRON command (see below).
  152.  
  153. -p xxxx        breakPoint.
  154.     Breakpoints are enabled, and one is set at address xxxx (in hex).
  155. Each time through the inner interpreter, the ip address is checked against
  156. this breakpoint address. If they match, "Breakpoint" is printed, along with
  157. the current stack pointer and the entire contents of the stack, with the
  158. topmost element at the left.
  159.  
  160. -c corename    set the core file name
  161.     The memory image will be read from this file instead of the default,
  162. which is usually "forth.core".
  163.  
  164. -b blockname    set the block file name
  165.     This file will be used as the block file for disk reads and writes,
  166. instead of the default block file, which is usually "forth.block".
  167.  
  168. -s savename    set the core-save file name
  169.     This file will be created or overwritten upon execution of the (SAVE)
  170. primitive (which is called by the SAVE command).  It will contain a core image
  171. (just like forth.core or the -c name) which reflects the current status at the
  172. time of the save. If this file is used as input (renamed to "forth.core" or
  173. used in -c later), the FORTH system will restart right where it left off.
  174. Note that -c and -s MAY use the same name.
  175.  
  176. DEPARTURES FROM THE figFORTH-79 STANDARD:
  177. ---------- ---- --- -------- -- --------
  178.  
  179. There are two features of the FORTH-79 standard which are unimplemented in
  180. this system: the <BUILDS ... DOES> construct a